/*
 *    Copyright 2009-2012 the original author or authors.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */
package org.apache.ibatis.type;

import java.sql.CallableStatement;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

import org.apache.ibatis.session.Configuration;

/**
 * @author Clinton Begin
 * @author Simone Tripodi
 */

/**
 * 类型处理器的基类
 * 在进行软件设计时提倡面向接口的设计，但接口只是一个接口，
 * 并不做任何实质性的操作，还需有一系列的实现才可以真正的达到目标。
 * BaseTypeHandler类便是对TypeHandler接口的初步实现，
 * 在实现TypeHandler接口的三个函数外，又引入了3个抽象函数用于null值的处理。
 * <p>
 * <p>
 * 也可以 覆盖type handler或者创建自己的type handler去处理mybatis不支持的或者非标准的数据类型。
 * <p>
 * 实现这个功能，只需要继承org.apache.ibatis.type.BaseTypeHandler类然后选择新的TypeHandler类和JDBC类型的对应关系即可。
 * <p>
 * 在官网中也给出了详细了示例，这里不再进行重复。其中用到了两个注解：MappedJdbcTypes 和 MappedTypes，我们可以看下这两个注解的定义文件：
 * <p>
 * 复制代码
 * {@Code
 *
 * @Retention(RetentionPolicy.RUNTIME)
 * @Target(ElementType.TYPE)
 * public @interface MappedJdbcTypes {
 * public JdbcType[] value();
 * }
 * }
 * {@Code
 * @Retention(RetentionPolicy.RUNTIME)
 * @Target(ElementType.TYPE)
 * public @interface MappedTypes {
 * public Class[] value();
 * }
 * }
 * 复制代码
 * <p>
 * <p>
 * MappedJdbcTypes传入的是JdbcType类型的（JdbcType是type包中的一个枚举类型），MappedTypes传入的Class类型。
 * <p>
 * 在声明完自己的类型转换之后，还需要让mybatis知道这些新的类型转换类，
 * 这可以通过在配置文件中添加typeHandlers节点来实现。可以添加一个类，也可以添加一个包中所有的类。
 *
 * <typeHandlers>
 * <typeHandler handler="org.mybatis.example.ExampleTypeHandler"/>
 * <package name="org.mybatis.example"/>
 * </typeHandlers>
 */
public abstract class BaseTypeHandler<T> extends TypeReference<T> implements TypeHandler<T> {

    protected Configuration configuration;

    public void setConfiguration(Configuration c) {
        this.configuration = c;
    }

    @Override
    public void setParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) throws SQLException {
        //特殊情况，设置NULL
        if (parameter == null) {
            if (jdbcType == null) {
                //如果没设置jdbcType，报错啦
                throw new TypeException("JDBC requires that the JdbcType must be specified for all nullable parameters.");
            }
            try {
                //设成NULL
                ps.setNull(i, jdbcType.TYPE_CODE);
            } catch (SQLException e) {
                throw new TypeException("Error setting null for parameter #" + i + " with JdbcType " + jdbcType + " . " +
                        "Try setting a different JdbcType for this parameter or a different jdbcTypeForNull configuration property. " +
                        "Cause: " + e, e);
            }
        } else {
            //非NULL情况，怎么设还得交给不同的子类完成, setNonNullParameter是一个抽象方法
            setNonNullParameter(ps, i, parameter, jdbcType);
        }
    }

    @Override
    public T getResult(ResultSet rs, String columnName) throws SQLException {
        T result = getNullableResult(rs, columnName);
        //通过ResultSet.wasNull判断是否为NULL
        if (rs.wasNull()) {
            return null;
        } else {
            return result;
        }
    }

    @Override
    public T getResult(ResultSet rs, int columnIndex) throws SQLException {
        T result = getNullableResult(rs, columnIndex);
        if (rs.wasNull()) {
            return null;
        } else {
            return result;
        }
    }

    @Override
    public T getResult(CallableStatement cs, int columnIndex) throws SQLException {
        T result = getNullableResult(cs, columnIndex);
        //通过CallableStatement.wasNull判断是否为NULL
        if (cs.wasNull()) {
            return null;
        } else {
            return result;
        }
    }

    //非NULL情况，怎么设参数还得交给不同的子类完成
    public abstract void setNonNullParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) throws SQLException;

    //以下3个方法是取得可能为null的结果，具体交给子类完成
    public abstract T getNullableResult(ResultSet rs, String columnName) throws SQLException;

    public abstract T getNullableResult(ResultSet rs, int columnIndex) throws SQLException;

    public abstract T getNullableResult(CallableStatement cs, int columnIndex) throws SQLException;

}
